---
layout: howTo
---
<!--
    Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements. See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership. The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License. You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied. See the License for the
    specific language governing permissions and limitations
    under the License.
-->

<!-- Main -->
<div id="main">

    <!-- Introduction -->
    <section id="intro" class="main special">
        <div class="">
            <div class="content align-left">
                <header class="major">
                    <h1><b>Deleted Messages Vault</b></h1>
                </header>

                <p>
                    This document will help you understand what is Deleted Messages Vault. And finally,
                    present to you, how to setup James Server with this feature.
                </p>

                <ul>
                    <li>What is Deleted Messages Vault</li>
                    <li>How to setup James with Deleted Messages Vault</li>
                    <li>How to administrate Deleted Messages Vault</li>
                </ul>

                <header class="major">
                    <h2><b>What is Deleted Messages Vault</b></h2>
                </header>

                <p>Deleted Messages Vault is a feature in James, it allows you to:</p>
                <ul>
                    <li>retain user deleted messages for some time</li>
                    <li>restore & export deleted messages by various criteria</li>
                    <li>permanently delete some retained messages</li>
                </ul>

                <p>
                    If Deleted Messages Vault is enabled, when users delete their mails, James will retain these mails into Deleted Messages Vault.
                    And only administrators can interact with this component via WebAdmin REST APIs.
                </p>
                <p>
                    One useful use of that feature is to allow an administrator to restore some mails an user may have deleted by accident.
                    However, mails are not retained forever as you have to configure a retention period before using it (we'll see later how to trigger the collection of mails).
                    It's also possible to permanently delete a mail if needed.
                </p>
                <p>
                    Deleted mails for exporting & restoring can be filtered via several criteria based on mail properties.
                    At the moment, these are supported mail properties for filtering:
                </p>
                <ul>
                    <li>deletion date(ISO-8601 Date String)
                        <ul>
                            <li>supports before or equals operator</li>
                            <li>supports after or equals operator</li>
                        </ul>
                    </li>
                    <li>delivery date(ISO-8601 Date String)
                        <ul>
                            <li>supports before or equals operator</li>
                            <li>supports after or equals operator</li>
                        </ul>
                    </li>
                    <li>recipients(List of string)
                        <ul>
                            <li>supports contains operator</li>
                        </ul>
                    </li>
                    <li>sender(String)
                        <ul>
                            <li>supports equal matching operator</li>
                        </ul>
                    </li>
                    <li>has attachment(Boolean)
                        <ul>
                            <li>supports equal matching operator</li>
                        </ul>
                    </li>
                    <li>subject(String)
                        <ul>
                            <li>supports equal matching operator</li>
                            <li>supports equal ignore case matching operator</li>
                            <li>supports contains matching operator</li>
                            <li>supports contains ignore case matching operator (with US locale)</li>
                        </ul>
                    </li>
                </ul>

                <header class="major">
                    <h2><b>How to setup James with Deleted Messages Vault</b></h2>
                </header>

                <p>
                    In this section, we will guide you to setup James with Deleted Message Vault by following below steps:
                </p>
                <ul>
                    <li>Enable Deleted Messages Vault</li>
                    <li>Make James uses Deleted Messages Vault by configuring Pre Deletion Hooks</li>
                    <li>Starting James with enabled Deleted Message Vault by docker compose</li>
                </ul>

                <header class="major">
                    <h3><b>Enable Deleted Messages Vault</b></h3>
                </header>

                <p>
                    To do this, you have to create a configuration file <b>deletedMessageVault.properties</b>, then put it into <b>conf</b> directory of James.
                    There are two available properties you may want to configure:
                </p>
                <ul>
                    <li>
                        <b>urlPrefix</b>: represent for the prefix of namespace Deleted Messages Vault will use to store deleted messages.
                    </li>
                    <li>
                        <b>retentionPeriod</b>: represent for the period deleted messages allowed to be stored in Deleted Messages Vault.
                    </li>
                </ul>

                <p>
                    Example:
                </p>
                <pre><code>
urlPrefix=cassandra://var/deletedMessages/vault
retentionPeriod=1 year
                </code></pre>
                <p>
                    More details about configuration & example is at <a href="/server/config-vault.html">Deleted Messages Vault Configuration</a>
                </p>

                <header class="major">
                    <h3><b>Make James uses Deleted Messages Vault by configuring Pre Deletion Hooks</b></h3>
                </header>

                <p>
                    By default, although Deleted Messages Vault has been configured, but, to make it really work, you still need to configure Pre Deletion Hooks to lets James use it.
                    Before deleting a mail in James, PreDeletionHooks will be triggered to execute all hooks. If all hook executions success, then James will process to delete that mail.
                    There is already a DeletedMessageVaultHook in James, its job to store deleted mails into Deleted Messages Vault. Thus, you need to configure this hook in listeners.xml configuration file.
                </p>

                <p>
                    Sample DeletedMessageVaultHook configuration:
                </p>
                <pre><code>
&lt;listeners&gt;
    &lt;listener&gt;
    ...
    &lt;/listener&gt;
    ...
    &lt;preDeletionHook&gt;
        &lt;class&gt;org.apache.james.vault.DeletedMessageVaultHook&lt;/class&gt;
    &lt;/preDeletionHook&gt;
&lt;/listeners&gt;
                </code></pre>
                <p>
                    More details about configuration & example is at <a href="/server/config-listener.html">Pre Deletion Hook Configuration</a>
                </p>

                <header class="major">
                    <h3><b>Starting James with enabled Deleted Message Vault by docker compose</b></h3>
                </header>

                <p>We will take James cassandra product for the example</p>

                <p>First, get template cassandra product configuration:</p>
                <pre><code>
$ git clone https://github.com/apache/james-project
$ cp -rf james-project/dockerfiles/run/guice/cassandra/destination/conf conf
                </code></pre>

                <p>Then create the keystore file in the conf/ directory with the default password <code>james72laBalle</code>
                <pre><code>
$ keytool -genkey -alias james -keyalg RSA -keystore conf/keystore
                </code></pre>

                <p>Second, modify deletedMessageVault.properties configuration file like an example at previous paragraph</p>

                <p>Third, modify listeners.xml to configure DeletedMessageVaultHook by adding preDeletionHook section at previous paragraph</p>

                <p>Fourth, We will create a local folder for holding data out of the container:</p>
                <pre><code>
mkdir var
                </code></pre>

                <p>Finally, starting a James Server by docker compose</p>
                <p>Getting James docker-compose.yml</p>
                <pre><code>
$ wget https://raw.githubusercontent.com/apache/james-project/master/dockerfiles/run/docker-compose.yml
                </code></pre>

                <p>Add the following volumes for james service:</p>
                <pre><code>
volumes:
  - $PWD/conf:/root/conf/
  - $PWD/var:/root/var/
                </code></pre>

                <header class="major">
                    <h2><b>How to administrate Deleted Messages Vault</b></h2>
                </header>

                <p>
                    These are supported WebAdmin features on top of Deleted Messages Vault.
                    You can have a look at WebAdmin Deleted Messages Vault document at <a href="https://james.apache.org/server/manage-webadmin.html#Deleted_Messages_Vault">here</a>
                </p>

                <header class="major">
                    <h3><b>WebAdmin Deleted Messages Vault exporting</b></h3>
                </header>

                <p>
                    This part is a bit special to you, you are able to choose which exporting mechanism to be used. At the moment there are one available exporting mechanism
                </p>
                <ul>
                    <li><b>localFile</b>: This is a simple exporting mechanism while with an export request, it retrieves deleted mails from Deleted Messages Vault,
                    then store them as a zip file in local file system in James Server. Then sending a mail with the absolute path of exported file to the targeted mail address.</li>
                </ul>
                <p>
                    You can configure which kind of export mechanism to use in James by specifying <b>blob.export.implementation</b> in blobStore.properties configuration file.
                    E.g:
                </p>
                <pre><code>
blob.export.implementation=localFile
                </code></pre>

                <p>
                    More details about configuration & example at <a href="/server/config-blob-expor.html">Blob Export Configuration</a>
                </p>
            </div>
            <footer class="major">
                <ul class="actions align-center">
                    <li><a href="index.html" class="button">go back to other how-tos</a></li>
                </ul>
            </footer>
        </div>
    </section>

</div>
